LLM应用全流程开发课件

Appearance

01-元搜索方案SearxNG ​

1. SearxNG 简介 ​

SearxNG 是一个开源的元搜索引擎，它可以帮助用户同时搜索多个搜索引擎的结果，并将这些结果整合展示。作为一个元搜索引擎，SearxNG 不存储用户的搜索历史，也不会跟踪用户的行为，因此它非常注重保护用户的隐私。

1.1 什么是元搜索引擎？ ​

元搜索引擎是一种特殊类型的搜索工具，它不维护自己的网页索引数据库，而是同时向多个搜索引擎发送查询请求，然后整合这些搜索结果并呈现给用户。这样用户就可以在一个页面上查看来自多个搜索引擎的结果，节省时间并获得更全面的信息。

1.2 SearxNG 的主要特点 ​

  • 隐私保护：不跟踪用户，不存储搜索历史
  • 自定义搜索：可以选择使用哪些搜索引擎
  • 开源：代码完全开源，可以自己部署和定制
  • 无广告：搜索结果中不包含广告
  • 多种搜索类别：支持网页、图片、视频、新闻等多种搜索
  • API支持：提供API接口，可以通过程序调用

2. 使用 Docker 部署 SearxNG ​

Docker 是一种容器化技术，可以让我们快速部署应用程序而不必担心环境配置问题。使用 Docker 部署 SearxNG 是最简单和推荐的方式。我们将使用官方提供的 searxng-docker 项目进行部署。

2.1 前提条件 ​

在开始之前，请确保你的系统上已经安装了以下软件：

  • Docker
  • Docker Compose
  • Git（用于克隆仓库）

如果你还没有安装 Docker，可以参考 Docker 官方文档 进行安装。

2.2 searxng-docker 项目组成 ​

官方的 searxng-docker 项目包含以下组件：

组件名称描述Docker 镜像
Caddy反向代理（自动创建 LetsEncrypt 证书）docker.io/library/caddy:2-alpine
SearxNG核心搜索引擎docker.io/searxng/searxng:latest
Valkey/Redis内存数据库（用于缓存）docker.io/valkey/valkey:8-alpine

这种组合设计使得 SearxNG 的部署既简单又安全，同时具有良好的性能表现。

2.3 基本部署步骤 ​

以下是使用官方 searxng-docker 项目部署 SearxNG 的步骤：

  1. 克隆 searxng-docker 仓库

    bash
    cd /usr/local
git clone https://github.com/searxng/searxng-docker.git
cd searxng-docker

  2. 编辑 .env 配置文件

    编辑 .env 文件设置主机名和联系邮箱：

    bash
    nano .env

    主要设置以下两个变量：

    • SEARXNG_HOSTNAME：设置为你的域名，例如 searx.example.com
    • LETSENCRYPT_EMAIL：设置为你的邮箱地址，用于 Let's Encrypt 证书通知

  3. 生成随机密钥

    生成一个随机密钥以增强安全性：

    bash
    sed -i "s|ultrasecretkey|$(openssl rand -hex 32)|g" searxng/settings.yml

    对于 macOS 用户，可以使用以下命令：

    bash
    sed -i '' "s|ultrasecretkey|$(openssl rand -hex 32)|g" searxng/settings.yml

  4. 编辑 SearxNG 配置文件

    bash
    nano searxng/settings.yml

    根据需要调整 SearxNG 的设置，如启用/禁用特定搜索引擎、修改默认设置等。

  5. 启动 SearxNG

    bash
    docker compose up -d

    这将在后台启动所有服务。如果你使用的是旧版 Docker Compose：

    bash
    docker-compose up -d

    注意：首次运行时，你需要从 docker-compose.yaml 文件中临时移除 SearxNG 服务的 cap_drop: - ALL 配置，以便成功创建 /etc/searxng/uwsgi.ini 文件。首次运行后，应将该配置重新添加以增强安全性。

2.4 部署方式选择 ​

官方提供了两种部署方式，你可以根据自己的需求选择：

方式一：包含 Caddy 的完整部署（推荐新手使用） ​

这是默认设置，无需额外配置，直接按照上述步骤执行即可。Caddy 会自动为你的域名申请并配置 Let's Encrypt 证书，处理 HTTPS 连接。

方式二：自带反向代理的部署（适合有经验的用户） ​

如果你已经有自己的反向代理（如 Nginx、HAProxy 等），可以使用这种方式：

  1. 修改 docker-compose.yaml 文件，移除 Caddy 相关部分（服务、卷等）
  2. 将你的反向代理指向 SearxNG 服务监听的端口（默认为 8080）
  3. 自行配置 TLS 证书
  4. 运行 docker compose up -d 启动服务

你可以通过设置环境变量 BIND_ADDRESS 来更改 SearxNG 在容器内监听的地址和端口（默认为 0.0.0.0:8080）。

2.5 使用 systemd 设置自启动服务 ​

如果你的系统使用 systemd，可以设置 SearxNG 作为系统服务自动启动：

  1. 复制服务模板文件

    bash
    cp searxng-docker.service.template searxng-docker.service

  2. 编辑服务文件

    如果你的安装路径不是 /usr/local/searxng-docker，需要编辑 searxng-docker.service 文件中的 WorkingDirectory 路径。

  3. 启用服务

    bash
    systemctl enable $(pwd)/searxng-docker.service

  4. 启动服务

    bash
    systemctl start searxng-docker.service

2.6 多架构支持 ​

SearxNG Docker 镜像支持多种架构，包括：

  • amd64（普通 x86_64 PC 和服务器）
  • arm64（如树莓派 4 使用 64 位系统）
  • arm/v7（如树莓派 3 和一些旧版 ARM 设备）

这意味着你可以在各种硬件平台上部署 SearxNG，包括普通 PC、服务器或者小型设备如树莓派。

2.7 日志查看与故障排除 ​

如果在使用过程中遇到问题，可以查看容器日志进行排查：

  • 查看所有容器的日志：

    bash
    docker compose logs -f

  • 查看特定容器的日志：

    bash
    # 查看 SearxNG 的日志
docker compose logs -f searxng

# 查看 Caddy 的日志
docker compose logs -f caddy

# 查看 Redis/Valkey 的日志
docker compose logs -f redis

2.8 更新 SearxNG ​

定期更新 SearxNG 可以获得新功能和安全修复。更新步骤如下：

bash
git pull
docker compose pull
docker compose up -d

如果你使用的是旧版 Docker Compose：

bash
git pull
docker-compose pull
docker-compose up -d

2.9 图片代理功能 ​

SearxNG 默认启用了图片代理功能，这有助于保护用户隐私。默认的内容安全策略（Content-Security-Policy）允许浏览器访问 ${SEARXNG_HOSTNAME} 和 https://*.tile.openstreetmap.org。

如果需要禁用图片代理，你需要修改 Caddyfile 文件。将 img-src 'self' data: https://*.tile.openstreetmap.org; 替换为 img-src * data:;。

3. 配置 Google Custom Search API ​

SearxNG 默认支持多种搜索引擎，但 Google 搜索可能需要额外配置，因为 Google 限制了直接爬取其搜索结果。不过，我们可以通过 Google Custom Search API 来解决这个问题。

3.1 获取 Google API 密钥和 CX ID ​

  1. 创建 Google API 密钥

    • 访问 Google Cloud Console
    • 创建一个新项目或选择已有项目
    • 在左侧菜单中，选择 "API 和服务" > "凭据"
    • 点击 "创建凭据" > "API 密钥"
    • 复制生成的 API 密钥，稍后会用到

  2. 启用 Custom Search API

    • 在 Google Cloud Console 中，选择 "API 和服务" > "库"
    • 搜索 "Custom Search API"
    • 点击 "启用"

  3. 创建自定义搜索引擎并获取 CX ID

    • 访问 Google Programmable Search Engine
    • 点击 "创建"
    • 按照提示设置你的搜索引擎
    • 在设置中找到 "搜索引擎 ID"（这就是你的 CX ID）
    • 复制这个 ID，稍后会用到

3.2 配置 SearxNG 使用 Google Custom Search ​

现在我们需要编辑 SearxNG 的配置文件来添加 Google Custom Search：

  1. 编辑配置文件

    编辑 searxng 目录下的 settings.yml 文件：

    bash
    nano searxng/settings.yml

    添加以下内容：

    yaml
    engines:
  - name: google_custom_search
    engine: json_engine
    shortcut: gcs
    search_url: "https://customsearch.googleapis.com/customsearch/v1?q={query}&key=YOUR_API_KEY&cx=YOUR_CX_ID"
    results_query: items
    url_query: link
    title_query: title
    content_query: snippet
    paging: true
    page_size: 10
    first_page_num: 1
    timeout: 3.0
    categories: general

    请将 YOUR_API_KEY 替换为你之前获取的 Google API 密钥，将 YOUR_CX_ID 替换为你的搜索引擎 ID。

  2. 重启 SearxNG 容器

    bash
    docker compose restart searxng

4. 扩展 API 接口支持 JSON 格式 ​

SearxNG 默认提供 HTML 格式的搜索结果，但我们可以配置它支持 JSON 格式，这对于开发应用程序特别有用。

4.1 配置支持 JSON 格式 ​

在 settings.yml 文件中添加以下配置：

yaml
search:
  formats:
    - html
    - json

完整的配置文件示例：

yaml
engines:
  - name: google_custom_search
    engine: json_engine
    shortcut: gcs
    search_url: "https://customsearch.googleapis.com/customsearch/v1?q={query}&key=YOUR_API_KEY&cx=YOUR_CX_ID"
    results_query: items
    url_query: link
    title_query: title
    content_query: snippet
    paging: true
    page_size: 10
    first_page_num: 1
    timeout: 3.0
    categories: general

search:
  formats:
    - html
    - json

保存文件后，重启 SearxNG 容器：

bash
docker compose restart searxng

5. 常见问题与解决方案 ​

5.1 SearxNG 无法启动 ​

检查 Docker 日志以查找错误信息：

bash
docker compose logs -f searxng

常见原因包括：

  • 配置文件格式错误（YAML 格式要求严格）
  • 端口冲突（8080 端口可能被其他应用占用）
  • 权限问题（确保配置目录有正确的权限）
  • 容器权限问题（首次运行时需要临时移除 cap_drop: - ALL 配置）

5.2 无法获取 Let's Encrypt 证书 ​

如果使用 Caddy 但无法自动获取 SSL 证书，检查：

bash
docker compose logs -f caddy

可能的原因：

  • 域名未正确解析到服务器 IP
  • 防火墙阻止了 80/443 端口
  • .env 文件中的域名或邮箱配置不正确

5.3 搜索结果为空 ​

如果配置了 Google Custom Search 但没有返回结果，可能的原因有：

  • API 密钥或 CX ID 不正确
  • API 配额已用完（Google 免费版每天有限制）
  • 配置文件中的 JSON 路径不正确

5.4 API 接口问题 ​

可以使用简单的 curl 命令测试 API：

bash
curl "http://your-domain.com/search?q=test&format=json"

如果返回错误，请检查：

  • format=json 参数是否正确
  • SearxNG 是否正确配置了 JSON 格式支持

6. 结语 ​

通过本教程，你已经学会了如何使用 Docker 部署 SearxNG 元搜索引擎，配置 Google Custom Search API，扩展接口支持 JSON 格式，以及如何管理容器和解决常见问题。SearxNG 是一个强大的工具，可以帮助你在保护隐私的同时获得更全面的搜索结果。

随着你对 SearxNG 的深入了解，你可以进一步探索更多高级功能，如自定义主题、添加更多搜索引擎、设置代理等。希望这个教程对你有所帮助！

参考资源：